What is mdast-util-toc?
The `mdast-util-toc` package is a utility for generating a Table of Contents (TOC) from Markdown Abstract Syntax Trees (MDAST). It is particularly useful for processing Markdown documents and extracting a structured TOC based on headings.
What are mdast-util-toc's main functionalities?
Generate TOC from MDAST
This feature allows you to generate a Table of Contents from a Markdown Abstract Syntax Tree. The code sample demonstrates how to convert a Markdown string into an MDAST, generate a TOC from it, and then convert the TOC back into a Markdown string.
const { toMarkdown } = require('mdast-util-to-markdown');
const { fromMarkdown } = require('mdast-util-from-markdown');
const { toc } = require('mdast-util-toc');
const markdown = '# Title\n## Subtitle\n### Sub-subtitle';
const tree = fromMarkdown(markdown);
const tocNode = toc(tree);
console.log(toMarkdown(tocNode.map));
Custom Heading Levels
This feature allows you to customize the depth of headings included in the TOC. The code sample demonstrates generating a TOC that includes only headings up to level 2.
const { fromMarkdown } = require('mdast-util-from-markdown');
const { toc } = require('mdast-util-toc');
const markdown = '# Title\n## Subtitle\n### Sub-subtitle';
const tree = fromMarkdown(markdown);
const tocNode = toc(tree, { maxDepth: 2 });
console.log(tocNode.map);
Custom TOC Heading
This feature allows you to specify a custom heading for the TOC. The code sample demonstrates generating a TOC with a custom heading 'Table of Contents'.
const { fromMarkdown } = require('mdast-util-from-markdown');
const { toc } = require('mdast-util-toc');
const markdown = '# Title\n## Subtitle\n### Sub-subtitle';
const tree = fromMarkdown(markdown);
const tocNode = toc(tree, { heading: 'Table of Contents' });
console.log(tocNode.map);
Other packages similar to mdast-util-toc
remark-toc
The `remark-toc` package is a plugin for the `remark` Markdown processor that generates a Table of Contents. It is similar to `mdast-util-toc` but is designed to be used directly within the `remark` ecosystem, making it easier to integrate if you are already using `remark`.
markdown-toc
The `markdown-toc` package generates a Table of Contents for Markdown files. Unlike `mdast-util-toc`, which works with MDAST, `markdown-toc` operates directly on Markdown strings, making it simpler to use for straightforward TOC generation without needing to parse the Markdown into an abstract syntax tree.
markdown-it-toc-done-right
The `markdown-it-toc-done-right` package is a plugin for the `markdown-it` Markdown parser that generates a Table of Contents. It is similar to `mdast-util-toc` in functionality but is designed to work within the `markdown-it` ecosystem, providing seamless integration if you are using `markdown-it` for Markdown processing.
mdast-util-toc
Generate a Table of Contents from mdast trees.
Installation
npm:
npm install mdast-util-toc
Usage
Dependencies:
var util = require('util')
var u = require('unist-builder')
var toc = require('mdast-util-toc')
Given a mdast tree:
var tree = u('root', [
u('heading', {depth: 1}, [u('text', 'Alpha')]),
u('heading', {depth: 2}, [u('text', 'Bravo')]),
u('heading', {depth: 3}, [u('text', 'Charlie')]),
u('heading', {depth: 2}, [u('text', 'Delta')])
])
Yields:
{ index: null,
endIndex: null,
map:
{ type: 'list',
ordered: false,
spread: true,
children:
[ { type: 'listItem', loose: true, spread: true, children: [Array] } ] } }
API
toc(node[, options])
Generate a Table of Contents from a Markdown document.
Looks for the first heading matching options.heading
(case insensitive,
supports alt/title attributes for links and images too), and returns a table
of contents for all following headings.
If no heading
is specified, creates a table of contents for all headings in
node
.
Links to headings are based on GitHub’s style.
Only top-level headings (those not in blockquotes or lists), are used.
(Change this default behavior by using option parents
as described below)
The given node is not modified.
options
options.heading
Heading to look for (string
), wrapped in new RegExp('^(' + value + ')$', 'i')
.
options.maxDepth
Maximum heading depth to include in the table of contents (number
, default:
6
),
This is inclusive, thus, when set to 3
, level three headings, are included
(those with three hashes, ###
).
options.tight
Whether to compile list-items tightly (boolean?
, default: false
).
options.parents
Allows headings to be children of certain node types.
Internally, it uses
unist-util-is to check.
Hence all types that can be passed in as first parameter can be used here,
including Function
, string
, Object
and Array.<Test>
.
Check
documentation
for details.
(default: the first parameter node
, which only allows top-level headings)
Example:
{
"parents": ["root", "blockquote"]
}
This would allow headings under either root
or blockquote
to be used.
Returns
An object representing the table of contents.
Properties
index
(number?
)
— Position of the heading
in node
. -1
if no heading
was found, null
if no heading was givenendIndex
(number?
)
— Position of the last node after heading
before the TOC starts.
-1
if no heading was found, null
if no heading was given,
same as index
if there are no nodes between heading
and the
first heading in the TOCmap
(Node?
)
— List node representing the generated table of contents.
null
if no table of contents could be created, either because
heading
didn’t exist, or because no following headings were found
Contribute
See contributing.md
in syntax-tree/mdast
for ways to get
started.
This organisation has a Code of Conduct. By interacting with this
repository, organisation, or community you agree to abide by its terms.
License
MIT © Jonathan Haines